# HP OpenView Service Desk

## version 4.5

## Dynamic forms

February 2006

© Copyright 2006 Hewlett-Packard Development Company, L.P.

## Content:

- Last-minute information
- Introduction
- Getting Started

- Insertion markers
- Form insertion rules

- Dynamic form changes only affect forms with predefined markers
- Dynamic form changes are evaluated page by page
- Dynamically added fields exclude those that are already on the same page of the original form
- Dynamically added tab pages are inserted on the left side of the form
- Fields that need to be dynamically added to a page without a marker are appended to the page
- Insertion markers on inserted forms are ignored

- Sub-forms
- The "Insert subform" action
- Configuring dynamic forms

- Create forms with fields for a specific context
- Make a form ready for form insertion
- Create a generic relation to associate field values with forms
- Set up mappings from item field values to forms
- Create a UI rule to trigger form insertion

- Known Errors and Limitations

## LAST-MINUTE INFORMATION

There is no last-minute information.

## INTRODUCTION

Before Service Pack 18, the form for each item type in Service Desk had a fixed layout. As a consequence, a form often contained many fields that were only used under specific circumstances. For example, some fields are only used when the item has a certain status, while other fields are only used when the item is in a given category. Even though an item may never be put in a state where those fields would need to have a value, they had to be put on the form anyway, simply for the reason that the item could potentially be put in such a state.
With many fields on a form, the likelihood of input in the wrong field increases: when there are many fields to choose from, it is very well possible that one field is mistaken for another. With many fields on a form, it is also likely that fields are overlooked, causing them to remain unused.
Dynamic forms are a new feature of Service Desk that make it possible to change the layout of the currently opened form based on values selected in the form. It allows the administrator to make fields visible only within the context in which they are needed, and not anywhere else.

## GETTING STARTED

The form layout change is controlled by a UI rule action that uses a table that maps field values to forms. This table is called a generic relation type. Whenever the appropriate field value is chosen, the UI rule searches the generic relation type for the field value. When the current field value is found, it effectively inserts the fields and tab-pages from the associated form into the opened form. Please refer to ITSM008088 for detailed information on Generic Relations.
To control the position on each tab page where fields from a form selected by the UI rule are put, a new layout element has been introduced, the insertion marker. Next to controlling the position where fields are to be inserted on each tab page, the insertion marker also serves as an indication that the current form is eligible to be changed by the new UI rule action.
The next sections describe the components that comprise the dynamic forms feature in more detail.

### Insertion markers

The insertion marker is a new type of field that you can use in the form designer. The form designer is accessed by going to the Administrator Console > Presentation > Forms; selecting an item category; and then opening a form. The next screenshot shows the Form Designer with the Insertion Marker field available in the Attributes list:
The insertion marker is used as more than a mere indication that a form may have fields added to it after the form was opened. It also marks the spot on the current page where fields from the inserted forms are added in case the tab page on which the insertion marker appears has the same name as a tab page of a form that is inserted.
The following screenshots illustrate how the insertion marker controls how one form is inserted into another, thus changing the layout dynamically. The first picture shows the form seen above as it is rendered when used to open a form. The second shows fields to add to this form. The third picture shows the two combined: the fields from the second form are inserted at the marker in the first form.
Every insertion marker must have a name. UI rules that change the currently opened form use the insertion marker name to identify any form on which they are to be used. A UI rule action that changes the current form will only trigger if it contains a reference to the name of the insertion marker on the current form. In the example above, the currently opened form would not have changed if the UI rule did not reference the insertion marker named "demo1" (as seen at the top of this section).
You can put multiple insertion markers on a single tab page. This allows multiple UI rules to manipulate part of the form. The following figure illustrates how a page may change through value changes on more than 1 field. Expanding on the previous example, it shows how introduction of an insertion marker called "demo2" allows a second rule to be changed.
You can use a maximum of 4 insertion markers on one form and each marker should be uniquely named.

### Form insertion rules

The section on "Insertion markers" contained a few examples on how dynamic form changes combine two form definitions to change the layout of the currently opened form based on user input. These examples demonstrate a few of the rules by which forms are combined. The next subsections summarize all the insertion rules.
The form designer has a clear distinction between the main page and the tab pages of a form. As far as the form insertion rules are concerned, the main page is simply the first of a series of pages. It is only different in the way it is rendered on screen and in the fact that the main page has no title. To the form insertion rules, the main page and the tab pages are conceptually the same. Therefore, there is no difference between the main page and the tab pages in terms of how they are affected by the insertion rules.

#### Dynamic form changes only affect forms with predefined markers

A Form will never be changed by a UI rule unless it contains an insertion marker. No Form will ever be changed until there are UI rules that change them. The currently opened Form is only changed when it contains an insertion marker that is referenced by a UI rule action that executes a form change. However, even though an insertion marker may appear only on a single page of a form, all the pages of the current form will be affected when a form changes, even the pages without markers.

#### Dynamic form changes are evaluated page by page

At the insertion marker, fields are inserted on the same tab page of the form selected by the UI rule (if any). If a tab page with a given title contains an insertion marker, but the inserted form does not have a tab page with the same title, the tab page on the resulting form will not change. This is because there is nothing to insert on that tab page. The following diagram illustrates this:
Pages on the form selected by the UI rule are added to the resulting form when there is no page with the same title on the original form definition. This is illustrated by the diagram below:

#### Dynamically added fields exclude those that are already on the same page of the original form

Fields from the form selected by the UI rule that are already on the same page of the currently opened form are not put on it again. The following diagram illustrates this:
Please note that if multiple markers are used and the UI rule selects a field to be inserted at the second marker that has already been inserted at the first marker, the field will appear on both markers. This is because the field was not on the original form definition.
If it is likely that two insertion markers on the same page introduce the same fields in a certain scenario, it makes much more sense to only introduce new tab pages using these markers.

#### Dynamically added tab pages are inserted on the left side of the form

If a tab page on the form selected by the UI rule does not appear on the currently opened form, it will be inserted as the left-most tab page. This is illustrated in the following figure:

#### Fields that need to be dynamically added to a page without a marker are appended to the page

If a tab page on the currently opened form has the same title as a tab page without the referenced insertion marker on the form selected by the UI rule, the fields from the tab page of the selected form will be appended to the tab page.
Effectively, this works the same as when the insertion marker is the last field of a page.

#### Insertion markers on inserted forms are ignored

When fields are inserted into a page, any insertion markers among the fields to add are stripped away. This prevents a new insertion marker from being introduced inside the section that was put in place of the insertion marker. In other words, it is not possible to nest insertion markers.

### Sub-forms

As explained in the previous chapter, dynamic forms combine form definitions to change forms on the fly. As a consequence, the number of form definitions can increase drastically with dynamic forms. Many of the new form definitions used for dynamic forms only have a use within the context of dynamic forms. These forms will never be used by themselves to open an item with. For that reason, forms are now divided into two types: regular and sub-forms.
Regular forms have always been in Service Desk. Sub-forms are a new type. These are different to regular forms only in that they cannot be used to open an item with. Another small difference is that the form designer will warn the administrator when a sub-form is saved that has an insertion marker on it. Insertion markers only have a use on regular forms: they are ignored on sub-forms.
Because the difference between regular and sub-forms is very small, any form can be changed into a sub-form and any sub-form can be turned back into a form. To change the type of a form, select the "Properties" from the menu in the form designer (which is what you see when you open a form from the Administrator Console > Presentation > Forms).
You are advised to define a form to be a sub-form when it is used within another form only.

### The "Insert subform" action

At the heart of the dynamic forms functionality is the "Insert subform" action. This action can be invoked by a UI rule to change the layout of the currently open form. The following screenshot shows the dialog in the UI rule wizard that is shown when an "Insert subform" action is selected. The meaning of the fields of the dialog that is shown in the screenshot is explained below.
The Name Field is used to describe this action. It is the name by which this action will be known in the UI rule wizard on the Actions page.
The blocked field allows you to (temporarily) disable this action.
The "Insertion marker" field will contain the names of all the insertion markers of Forms defined for same item category as for which the current UI rule is defined, in as far they are not used by other "Insert subform actions". For example, for Person, three forms are defined. The first form contains an insertion marker called "mark1", the second one has a marker called "mark2" and the third one a marker called "mark3". For Organization, a form is defined with an insertion marker called "m1". When you define an "Insert subform" action for a Person, the dropdown box will contain "mark1", "mark2", and "mark3". It will not contain "m1" because it is on a form that is used in a different item category. Once you have defined a UI rule for Person that executes an "Insert subform" action that uses "mark1", the UI rule wizard will not show "mark1" in any dialog defining an "Insert subform" action for another UI rule on Person. This is to prevent two UI rules that change the current form from intervening with one another.
"Paths to try" is a way to select multiple values easily with Generic Relations. Each path has a "Source field" and a "Relation type".

When you click on the "Source field", it will show a dropdown box of all fields of the current item type for which outgoing generic relation types have been defined to a form. Once a value is selected for the "Source field", the "Relation type 1" field will become active. It will be populated by all outgoing generic relation types from the field selected as "Source" field to Form. Effectively, these are mapping tables, specifying which form to use whenever a given value is active.
When a value is chosen for the "Relation type 1" field, the "Add to list" button becomes active. When pressed, the value selected in the "Relation type 1" field is added to the "Paths to try" box.
Effectively, the "Paths to try" can be considered a secondary type of condition of the UI rule. For this reason, you are advised to use the field that is selected as "Source field" as part of the condition of the UI rule that triggers this action as well. In the condition, it should only be ascertained that the field has a value. The administrator should not limit execution of the UI rule that controls dynamic form changes based on any particular value of a particular field, otherwise the "Insert subform" action will not be triggered when any other than the value in the condition is chosen in the form.
For example, a generic relation type defines relations between the Status field and Forms. This generic relation type is used in an "Insert subform" action. The UI rule that calls this action should then include the condition "Status is anything". If the condition would include "Status equals 'somespecificvalue'", the only generic relation in the generic relation type that will be used is the one that relates from 'somespecificvalue' to a form. In this case, even when the generic relation type defines other outgoing relations of the Status field as well, they would never be used, because the action is never executed when another value is chosen.

Note: You can add multiple paths but only the first match is used.

### Configuring dynamic forms

This section outlines the steps to take to configure dynamic forms.

#### Create forms with fields for a specific context

Go to Administrator Console > Presentation > Forms; select an item category; right-click to create a new form:

- This opens a window like the one seen below:
- As name, use a prefix that includes the item type (service call, problem, CI, etc) for which the form is created. This will make it easier to identify the form later on. Once you have entered a name, the OK button will be activated.
- Check the sub-form checkbox.
- When you press the OK button, you will enter the Form Designer. Add tab-pages and fields as required. It is usually easiest for the users when a dynamic form change introduces new tab pages.

Note: It is recommended to use type name as prefix which will make it easier to locate the subform when defining relations. For example, use "subsc_" as the prefix for Service Call subforms.

#### Make a form ready for form insertion

Go to Administrator Console > Presentation > Forms, edit an existing form (that is not a sub-form) or create a new form.

- This opens a form like the one seen below:
- Place an insertion marker field on any page of the form. As explained earlier in this document, the insertion marker indicates the spot on that page where fields will be inserted from the page with the same page title on a sub-form (if any). Insertion markers must have a name. This name is unique per page, because this name uniquely identifies a spot on the page where new fields must be inserted. You can use a maximum of 4 uniquely named insertion markers on a form.
- Make sure that the field that you want form changes to depend upon is present on this form.

#### Create a generic relation to associate field values with forms

Go to Administrator Console/Data/Codes/General/Generic Relation Type, right-click to create a new generic relation type.

- This opens a dialog like the one seen in the screenshot below:
- As "from item", select a field of the item category for which you have been editing Forms up to this point. This field will determine which sub-form is to be used. For example, Service Call Status, CI Category, Classification. Some fields appear in multiple item categories (e.g. Folder), so they do not have a prefix indicating the item type in the "from item" list.
- As name, it is recommended to use the convention "<field> to form" where <field> is substituted by the name of the field that is the "from item" side of the generic relation type (in other words, for which the generic relation type is an outgoing one).
- As "to item", select "Form".

Keep the generic relation type open for the next step.

#### Set up mappings from item field values to forms

In the generic relation type created in the previous step, press the "Add" button in the right pane.

- This opens a dialog like the one seen in the screenshot below:
- Choose a from-item from the list of values. If a "from item" value is used more than once, only the first "to-item" value found will be used by the dynamic form.
- Choose a to-item from the list of forms. Forms hold no reference to the item for which they are created. Therefore, you will see a list of all forms when you set up the mapping here. It helps to sort on the sub-form property first, next on the name. If a specific prefix is used for subforms, first type the prefix (e.g. "subsc_") in lookup field and then click the quick find button. This will help to limit the list of forms.

#### Create a UI rule to trigger form insertion

Go to Administrator Console/Business logic/UI rules. Select the item category for which you created the sub-forms. Create a new UI rule:

- As triggers, select all except "when a form is closed", press next.
- As condition, select "<field> is anything", where <field> is substituted by the name of the field used as "from item" when you created the generic relation type earlier. Press next.
- Add an "Insert subform" action as seen in the screenshot below.
- The value for Name field is the text that you will see in the list on the actions page of the UI Rule wizard. It can be anything you like.
- The dropdown box of the "Insertion marker" field will contain all names of insertion markers (such as the one added to the default form, as described in the section "Make a form ready for form insertion") for which no "Insert subform" action has been defined yet. In other words, as soon as you define an "Insert subform" action for a marker called "mark1", you can no longer create any other "Insert subform" action to operate on the same insertion marker.
- As "source field", select the field name used as "from item" when you created the generic relation type earlier.
- Press the icon to the right of the relation type field. If you only have one generic relation type defined to map fields values to forms, this value will be selected automatically, otherwise you will see a list of generic relation types. Alternatively, you could use advance find to add a generic relation type.
- Press "add to list". Next, press ok to save the "Insert subform" action.
- Press next in the UI rule wizard. (Note: in case you selected the event type "when a form is closed" despite the instructions not to earlier, the UI rule wizard will complain that you may not use this event type in combination with an "Insert subform" action. You will then have to go back a couple of pages to deselect this event type).
- Choose a name and rule category, press finish.

The form you changed in the step "Make a form ready for insertion" will now respond to changes of values in the field you selected when you carried out the instructions in the step "Set up mappings from item field values to forms".

## KNOWN ERRORS AND LIMITATIONS

- It is possible to define a UI rule so that the same rule has multiple "Insert Subform" actions that update the same insertion marker. The UI rule wizard prevents another UI rule from having an "Insert subform" action that updates an insertion marker that is aleady used by another "Insert subform" action in another UI rule. Unfortunately, the check fails when the two actions are part of the same rule. While this will not break the functioning of the UI rule, it may have unexpected results because it is not determined which action is executed first.
- It is possible to delete a generic relation type that is referenced by an "Insert subform" action. For now, you should examine your rules to see if it uses a specific generic relation type before you decide to remove it.
- While a form is being changed on screen, users may temporarily see some fields appear as writable that are supposed to be read-only according to the permissions granted by the current user's roles. It is purely a cosmetic issue: there is no way for the user to abuse the fact that the fields seem writable. Furthermore, once the form change is complete, all read-only fields will be grayed out as expected.
- ACES cannot be used to migrate generic relation type instances defined on one Service Desk database to another. For now, you will have to recreate these manually when migrating this part of the Service Desk configuration from a staging to a production environment.